home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / asmutil / afloat.zip / AFLOAT.DOC next >
Text File  |  1988-03-16  |  13KB  |  259 lines
  1. User's guide to single-precision floating-point library FLOAT.LIB.
  2. Assembly Language Version.
  3. Copyright Bob Kline 1988
  4.  
  5. General notes:
  6.         One of the frustrations which assembly-language pro-
  7.         grammers occasionally encounter is the lack of in-
  8.         structions for dealing with floating-point operations.
  9.         Even in architectures where a math coprocessor is
  10.         designed to handle floating-point work efficiently,
  11.         the problem is often still not resolved, as it fre-
  12.         quently turns out that most machines are not equipped
  13.         with the extra math chip.  A good example is the IBM
  14.         PC family and clones, which can use a math coprocessor
  15.         to do floating-point work in hardware.  Only a very
  16.         small percentage of these computers are equipped with
  17.         such a coprocessor.
  18.  
  19.         This library consists of procedures for performing
  20.         basic single-precision floating-point operations in
  21.         assembly language programs written for the 808x family
  22.         of computers not equipped with a math coprocessor.
  23.         The procedures have been built for use with the 'small'
  24.         memory model, that is, for programs which use 16-bit
  25.         pointers and near procedure calls.  It should not be
  26.         an inordinantly difficult task to rework the code for
  27.         other models, as (with the exception of the procedures
  28.         which take in or produce strings: ATOF, FTOA, and FTOE),
  29.         all parameters and results are passed in hardware
  30.         registers, and the new simplified .MODEL directives (a
  31.         feature of MASM 5.0) have been used.  Although at this
  32.         point only the most fundamental operations have been
  33.     provided, it is hoped that a subsequent student or
  34.         team of students will build on this foundation, adding
  35.         some of the geometric and exponential functions.
  36.  
  37.         All floating-point values handled by the library are
  38.         4-byte single-precision reals in the format established
  39.         by the IEEE standard.  The details of this format are as
  40.         follows: the sign is stored in the most significant bit
  41.         (bit 31) of the 32-bit representation (set to 1 for a
  42.         negative number, reset to 0 for a positive value); the
  43.         exponent is stored as an eight-bit value in bits 23
  44.         through 30, and is biased by adding 127 to its actual
  45.         value -- that is, a (binary) exponent of 0 is
  46.         represented as 127, -1 as 126, 1 as 128, and so on; the
  47.         fractional portion of the mantissa is represented in
  48.         bits 0 through 22; except for a value of 0.0, which is
  49.         represented with all 32 bits of the float reset to
  50.         zeros, the integer bit of the mantissa is understood to
  51.         be 1, and does not therefore need to be explicitly
  52.         stored as part of the number.  In terms of decimal
  53.         representation, this format can handle a range from an
  54.         exponent of -38 through +38, with a precision of at
  55.         least 7 (possibly 8) digits.
  56.  
  57.         Names for the procedures have been chosen which would
  58.         not conflict with those used by the math coprocessor.
  59.         So, for example, the routine to add to floating-point
  60.         numbers is called F_ADD rather than FADD.
  61.  
  62.         The following descriptions give details about how each
  63.         of the procedures works, including which registers are
  64.         used for incoming and outgoing values, assumptions made
  65.         by the procedures, and behavior with error conditions.
  66.         The list is headed by a description of _errno, a global-
  67.         ly available variable used as a flag by several of the
  68.         procedures to indicate that an error has occurred.
  69.  
  70.         A companion file is provided, FLOAT.INC, which can be 
  71.     included in the source code for modules using this li-
  72.     brary, giving the assembler access to the table of ex-
  73.     ternal names which it will need for finding the library
  74.     routines.
  75.  
  76. *---------------------------------------------------------------*
  77. EXTRN _errno:WORD
  78.         Used by several of the math routines to signal that an
  79.         error has taken place.  Two possible values are EDOM
  80.         (33), which indicates that an invalid parameter has been
  81.         passed, such as a divisor of zero; and ERANGE (34),
  82.         which indicates that the result does not fall within the
  83.         range of values which can be represented by the type
  84.         specified for the result.  The calling routine should
  85.     reset _errno to zero before the math operation is invoked
  86.         to ensure that a subsequent check is not looking at the
  87.         results of an error from an earlier operation.
  88.  
  89. *---------------------------------------------------------------*
  90. ATOF
  91.         Converts the string pointed to by SI to a floating-
  92.         point value.  Leading spaces are skipped.  The string
  93.         contains an optional sign, followed by a series of
  94.         decimal digits, possibly with a decimal point at any
  95.         point in the series of digits, followed optionally
  96.         by 'e' or 'E' and a (possibly signed) integer
  97.         indicating the exponent.  The calling function in
  98.         responsible for making sure that the input string
  99.         actually contains a valid floating-point value.  On
  100.         return DX:AX contain the 4-byte real result; in
  101.         addition, the values in registers BP, SI, DI, BX,
  102.         and CX are destroyed.
  103.  
  104. *---------------------------------------------------------------*
  105. ITOF
  106.         Converts the 2-byte integer value passed in the AX
  107.         register to a 4-byte real and stores the result in
  108.         DX:AX.  In addition, the value in CX is changed.
  109.  
  110. *---------------------------------------------------------------*
  111. F_ADD
  112.         Adds the 4-byte real passed in CX:BX to the 4-byte real
  113.         passed in DX:AX and stores the result in DX:AX.  If the
  114.     result will not fit in a 4-byte real, _errno is set to
  115.         ERANGE, and the resulting value in DX:AX is
  116.         unpredictable.  In addition to DX:AX, registers BX, CX,
  117.         SI, DI, and BP and changed.
  118.  
  119. *---------------------------------------------------------------*
  120. F_SUB
  121.         Subtracts the 4-byte real in CX:BX from the 4-byte real
  122.         passed in DX:AX, storing the result in DX:AX.  If the
  123.         result will not fit in a 4-byte real, _errno is set to
  124.         ERANGE, and the value in DX:AX is unpredictable.  In
  125.         addition to the DX:AX registers used for the return
  126.         value, the CX, BX, DI, SI, and BP registers will be
  127.         altered.
  128.  
  129. *---------------------------------------------------------------*
  130. FABSVAL
  131.         Takes the 4-byte real value contained in DX:AX and makes
  132.         it positive; no other registers are affected.
  133.  
  134. *---------------------------------------------------------------*
  135. FBINTODEC
  136.     Takes a 4-byte real value and breaks down the compo-
  137.     nents into their decimal equivalents.  The real value
  138.     passed to the procedure in the DX:AX registers.  On
  139.     return the DX:AX registers contain the mantissa, with
  140.     a decimal portion understood to be at the end, the CX
  141.     register contains the sign in its low bit, and the BX
  142.     register contains the signed, unbiased decimal expo-
  143.     nent.  In addition, the values in the SI and DI re-
  144.     gisters are destroyed.
  145.  
  146. *---------------------------------------------------------------*
  147. FCMP
  148.         Compares 4-byte real value in DX:AX with 4-byte real
  149.         value in CX:BX to determine which is the larger.  On
  150.         return AX contains a positive integer if the value in
  151.         DX:AX is greater than that in CX:BX, a negative integer
  152.         if DX:AX is less than CX:BX, and zero if the two values
  153.         are equal.  In addition to the return value in AX,
  154.         registers DX, CX, BX, SI, DI, and BP are changed.
  155.  
  156. *---------------------------------------------------------------*
  157. FDECTOBIN
  158.     Converts the decimal components of a floating-point
  159.     number to a 4-byte real in IEEE format.  On entry, DX:AX
  160.     contain the mantissa with the decimal point understood
  161.     to be at the end, CX contains the sign in its low bit,
  162.     and